feat(state)!: add the ability to submit blobs in parallel #4595

evan-forbes · 2025-09-26T05:35:20Z

This is a draft until we get an official release from app, but it would be super useful for me to get reviews from node folks as I do not know what I'm doing in this repo 😅

Currently, node automatically submits blobs asynchronously. Meaning we can submit multiple per block, but the ordering isn't guaranteed.

This adds the ability to submit blobs in parallel and the ability to submit blobs synchronously.

Synchronous (workers == 1) has a single worker that has a queue of blobs. It submits the blob, waits for it to be confirmed, and then submits the next blob in the queue. This doesn't guarantee order, as its possible a tx fails or gets evicted and the next blob in the queue does not. However most importantly avoids sequence mismatches since we're only ever submitting a single blob from an account at once. The account that is submitting the blob here is the one passed to TxClient.

Parallel submission works in the exact same way, except there are more than one worker. In order to manage these accounts, it creates new ones and grants them a feegrant by submitting a single transaction for all accounts that don't already have this. This ofc means that different accounts will submit blobs. All accounts are in the same keyring that has the main account.

docs/adr/adr-009-public-api.md

evan-forbes · 2025-09-30T03:16:01Z

state/core_access.go

-	response, err := client.SubmitPayForBlobWithAccount(ctx, account.Name(), libBlobs, opts...)
+	response, err := client.SubmitPayForBlob(ctx, libBlobs, opts...)


this is the bulk of the change

renaynay

mostly good w me, mostly about namings

renaynay · 2025-09-30T11:24:55Z

nodebuilder/state/config.go

+	// parallel submissions. This means that blobs can be submitted by multiple different
+	// signers, and that blobs will not be submitted on chain in the original sending order.
+	// This is highly recommended for high throughput chains.
+	WorkerAccounts int


Suggested change

WorkerAccounts int

TxWorkerAccounts int

renaynay · 2025-09-30T11:26:52Z

nodebuilder/state/flags.go

 	}
+
+	if cmd.Flag(txWorkerAccountsFlag).Changed {
+		value, err := strconv.Atoi(cmd.Flag(txWorkerAccountsFlag).Value.String())


we can fatal out on err here

renaynay · 2025-09-30T11:32:26Z

state/core_access.go

 		ca.estimatorConn = estimatorConn
 	}

+	if ca.workerAccounts > 0 {


maybe > 1 since default is 1

renaynay · 2025-09-30T11:55:24Z

state/option.go

+// WithWorkerAccounts configures the CoreAccessor to manage the provided number of
+// worker accounts via the TxClient. A value of zero leaves parallel
+// submission disabled.
+func WithWorkerAccounts(workerAccounts int) Option {


Suggested change

func WithWorkerAccounts(workerAccounts int) Option {

func WithTxWorkerAccounts(workerAccounts int) Option {

renaynay · 2025-10-01T08:35:39Z

state/core_access.go


-	response, err := client.SubmitPayForBlobWithAccount(ctx, account.Name(), libBlobs, opts...)
+	var response *user.TxResponse
+	if account.Name() == ca.defaultSignerAccount {


Note that this is ugly, but until we have TxClient refactor, it will remain ugly.

Also, once we get Signer field in TxResponse, we should implement unit test for this. For now, manually tested.

renaynay · 2025-10-01T09:01:31Z

For documentation purposes (cc @jcstein)

This PR introduces parallel transaction submission lanes #5776.

Parallel Transaction Submission Lanes

Node runners enable this feature by setting TxWorkerAccounts in the state config:

  [State]
    DefaultKeyName = "my_celes_key"
    DefaultBackendName = "test"
    EstimatorAddress = ""
    EnableEstimatorTLS = false
    TxWorkerAccounts = 8

TxWorkerAccounts defines how many parallel lanes the TxClient will initialize. These lanes are subaccounts funded by the default account to submit PayForBlob transactions in parallel, bypassing account sequence limits and enabling higher throughput (≥ TxWorkerAccounts PayForBlob txs per block).

Example: TxWorkerAccounts = 8 → 7 funded subaccounts + 1 default account, allowing at least 8 PayForBlob txs per block.

⚠️ Important Notes

Not suitable for implementations requiring sequential ordering.
Only valid for unordered transaction workflows.
Parallel submission works only with the default account. Specifying another account in TxConfig bypasses it.

Synchronous Submission

TxWorkerAccounts of 1 → synchronous/queued transaction submission.

Each tx queues until the previous is confirmed.
Preserves ordering and avoids sequence mismatches.
Throughput: ~1 PayForBlob tx per block.

⚠️ Important Notes

If an account other than the default account is specified in TxConfig, the queue is bypassed and txs enter the mempool directly without waiting on confirmations.

Default Behavior (immediate transaction submission)

TxWorkerAccounts defaults to 0 → queued submission disabled. All PayForBlob txs are submitted immediately. This is exactly the same behaviour as before with txs entering the mempool directly without waiting on confirmations.

Wondertan

LGTM

We should also mark this change as (config) breaking btw

evan-forbes · 2025-10-01T11:58:30Z

generally correct, but I could see room for confusion

This feature CANNOT be used by implementations that need sequential ordering of transactions.

The default TxWorkerAccounts value is 1.
A value of 1 would indicate to the TxClient not to enable parallel tx submission and all PayForBlob transactions

might be worth refactoring this to state the 1 thing first, as the "cannot use this new feature" thing might cause confusion. ofc, we can use this new feature and it actually provides more sequential ordering than before since we don't need to resign. The current TxClient is actually incapable of sequential ordering as is fwiw.

The bigger diff here might be that the blobs come from different accounts.

This preserves old behaviour with the caveat that now, users will still be able to call SubmitPayForBlob multiple times, but every call to this endpoint will queue up transactions to be submitted by the default account. The TxClient submits the blob, waits for it to be confirmed, and then submits the next blob in the queue. This doesn't guarantee order, as its possible a tx fails or gets evicted and the next blob in the queue does not. However most importantly avoids sequence mismatches since we're only ever submitting a single blob from an account at once.

imo it would clearer to state something along the lines of:

Setting a value to 0 preservers the previous behavior of submitting multiple blobs from the same account. This is not recommended due to hitting many sequence mismatches and low throughput. Setting a value of 1 is breaking in that blobs are queued and submitted one by one. This avoid sequence mismatches and preserves the original order of the blobs in almost all cases.

renaynay · 2025-10-01T12:01:30Z

Setting a value to 0 preservers the previous behavior of submitting multiple blobs from the same account. This is not recommended due to hitting many sequence mismatches and low throughput. Setting a value of 1 is breaking in that blobs are queued and submitted one by one. This avoid sequence mismatches and preserves the original order of the blobs in almost all cases.

@evan-forbes we do not even allow a TxWorker count of 0 -- we default to 1 worker. We enforce this

evan-forbes

I can't approve my own PR but I approve the changes

cmwaters

Change looks good. I only have a few nits

cmwaters · 2025-10-08T10:19:57Z

nodebuilder/state/config.go

+	// TxWorkerAccounts defines how many accounts the tx client manages for
+	// PayForBlob submissions.
+	//   - Value of 0 submits transactions immediately (without a submission queue).
+	//   - Value of 1 uses synchronous submission (submission queue with default
+	//     signer as author of transactions).
+	//   - Value of > 1 uses parallel submission (submission queue with several accounts
+	//     submitting blobs). Parallel submission is not guaranteed to include blobs
+	//     in the same order as they were submitted.
+	TxWorkerAccounts int


nit:

Suggested change

// TxWorkerAccounts defines how many accounts the tx client manages for

// PayForBlob submissions.

// - Value of 0 submits transactions immediately (without a submission queue).

// - Value of 1 uses synchronous submission (submission queue with default

// signer as author of transactions).

// - Value of > 1 uses parallel submission (submission queue with several accounts

// submitting blobs). Parallel submission is not guaranteed to include blobs

// in the same order as they were submitted.

TxWorkerAccounts int

// TxWorkerAccounts is used for queued submission. It defines how many accounts the

// tx client uses for PayForBlob submissions.

// - Value of 0 submits transactions immediately (without a submission queue).

// - Value of 1 uses synchronous submission (submission queue with default

// signer as author of transactions).

// - Value of > 1 uses parallel submission (submission queue with several accounts

// submitting blobs). Parallel submission is not guaranteed to include blobs

// in the same order as they were submitted.

TxWorkerAccounts int

cmwaters · 2025-10-08T10:21:50Z

nodebuilder/state/flags.go

+		"specifies how many accounts the TxClient manages for PayForBlob submission.\n"+
+			"0 disables parallel submission. Values greater than 1 automatically create "+
+			"\"parallel-worker-*\" accounts and grant them fees using the default signer.",


nit: specify behaviour of when this is set to 1

Suggested change

"specifies how many accounts the TxClient manages for PayForBlob submission.\n"+

"0 disables parallel submission. Values greater than 1 automatically create "+

"\"parallel-worker-*\" accounts and grant them fees using the default signer.",

"is used for queued submission. It defines how many accounts the TxClient uses for PayForBlob submission.\n"+

"0 disables queued submission. 1 uses the default account. Values greater than 1 automatically create "+

"\"parallel-worker-*\" accounts and grant them fees using the default signer.",

cmwaters · 2025-10-08T10:22:02Z

nodebuilder/state/flags.go

 	)
+	flags.Int(
+		txWorkerAccountsFlag,
+		1,


Is this the default? Don't we want it to be 0?

cmwaters · 2025-10-08T10:23:07Z

state/core_access.go

+	//   - Value of > 1 uses parallel submission (submission queue with several accounts
+	//     submitting blobs). Parallel submission is not guaranteed to include blobs
+	//     in the same order as they were submitted.
+	workerAccounts int


nit: for consistency

Suggested change

workerAccounts int

txWorkerAccounts int

refactor + fix(state): Rename opts + cfg param && honour submission path thru SubmitPayForBlobWithAccount if non-default account specified in TxConfig refactor(state): TxWorkerAccounts == 0 --> preserve default behaviour

jcstein · 2025-10-09T15:46:53Z

Is this replaced by #4620?

evan-forbes self-assigned this Sep 26, 2025

evan-forbes added this to core/app Sep 26, 2025

github-project-automation bot moved this to Needs Triage in core/app Sep 26, 2025

github-actions bot added external Issues created by non node team members kind:break! Attached to breaking PRs labels Sep 26, 2025

evan-forbes moved this from Needs Triage to In Progress in core/app Sep 26, 2025

evan-forbes commented Sep 30, 2025

View reviewed changes

renaynay reviewed Sep 30, 2025

View reviewed changes

renaynay force-pushed the evan/besttx/parallel-0 branch from 1f32639 to 12ed37e Compare September 30, 2025 14:53

renaynay approved these changes Oct 1, 2025

View reviewed changes

renaynay marked this pull request as ready for review October 1, 2025 08:35

renaynay requested review from Wondertan, adlerjohn, gupadhyaya, liamsi, vgonkivs and walldiss as code owners October 1, 2025 08:35

Wondertan approved these changes Oct 1, 2025

View reviewed changes

Wondertan changed the title ~~feat: add the ability to submit blobs in parallel~~ feat(state)!: add the ability to submit blobs in parallel Oct 1, 2025

renaynay marked this pull request as draft October 1, 2025 13:02

evan-forbes commented Oct 2, 2025

View reviewed changes

cmwaters approved these changes Oct 8, 2025

View reviewed changes

feat: add the ability to submit blobs in parallel

c392d26

refactor + fix(state): Rename opts + cfg param && honour submission path thru SubmitPayForBlobWithAccount if non-default account specified in TxConfig refactor(state): TxWorkerAccounts == 0 --> preserve default behaviour

renaynay force-pushed the evan/besttx/parallel-0 branch from 01d2ba2 to c392d26 Compare October 8, 2025 15:03

renaynay mentioned this pull request Oct 8, 2025

feat(state): Introduce queued submission #4620

Merged

evan-forbes closed this Oct 20, 2025

github-project-automation bot moved this from In Progress to Done in core/app Oct 20, 2025

		response, err := client.SubmitPayForBlobWithAccount(ctx, account.Name(), libBlobs, opts...)
		response, err := client.SubmitPayForBlob(ctx, libBlobs, opts...)

	func WithWorkerAccounts(workerAccounts int) Option {
	func WithTxWorkerAccounts(workerAccounts int) Option {

feat(state)!: add the ability to submit blobs in parallel #4595

feat(state)!: add the ability to submit blobs in parallel #4595

Conversation

evan-forbes commented Sep 26, 2025

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

renaynay left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

renaynay commented Oct 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

For documentation purposes (cc @jcstein)

Parallel Transaction Submission Lanes

⚠️ Important Notes

Synchronous Submission

⚠️ Important Notes

Default Behavior (immediate transaction submission)

Uh oh!

Wondertan left a comment

Choose a reason for hiding this comment

Uh oh!

evan-forbes commented Oct 1, 2025

Uh oh!

renaynay commented Oct 1, 2025

Uh oh!

evan-forbes left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cmwaters left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jcstein commented Oct 9, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

renaynay commented Oct 1, 2025 •

edited

Loading

evan-forbes left a comment •

edited

Loading